package com.it.schoolhomeos.service;

import com.it.schoolhomeos.dto.ExamGradeDTO;
import com.it.schoolhomeos.dto.StudentExamGradeDTO;
import com.it.schoolhomeos.dto.StudentGradeDTO;
import com.it.schoolhomeos.entity.Grade;
import org.springframework.data.domain.Page;

import java.util.List;
import java.util.Map;

/**
 * 成绩服务接口
 * 
 * 定义成绩相关的业务逻辑操作
 * 包括成绩记录的查询、创建、更新和删除等功能
 */
public interface GradeService {
    
    /**
     * 获取成绩记录（分页）
     * 
     * @param studentId 学生ID
     * @param subject 科目
     * @param examId 考试ID
     * @param page 页码
     * @param size 每页大小
     * @return 分页的成绩记录
     */
    Page<Grade> getGrades(Long studentId, String subject, Long examId, int page, int size);
    
    /**
     * 获取学生成绩记录
     * 
     * @param studentId 学生ID
     * @param subject 科目
     * @param examId 考试ID
     * @return 成绩记录列表
     */
    List<Grade> getStudentGrades(Long studentId, String subject, Long examId);
    
    /**
     * 根据ID获取成绩记录
     * 
     * @param id 成绩记录ID
     * @return 成绩记录
     */
    Grade getGradeById(Long id);
    
    /**
     * 保存成绩记录
     * 
     * @param grade 成绩记录
     * @return 保存后的成绩记录
     */
    Grade saveGrade(Grade grade);
    
    /**
     * 更新成绩记录
     * 
     * @param grade 成绩记录
     * @return 更新后的成绩记录
     */
    Grade updateGrade(Grade grade);
    
    /**
     * 删除成绩记录
     * 
     * @param id 成绩记录ID
     */
    void deleteGrade(Long id);

    /**
     * 获取班级成绩记录（分页）
     * 
     * @param classId 班级ID
     * @param subject 科目
     * @param examId 考试ID
     * @param page 页码
     * @param size 每页大小
     * @return 分页的成绩记录
     */
    Page<Grade> getClassGrades(Long classId, String subject, Long examId, int page, int size);

    /**
     * 创建成绩记录
     * 
     * @param grade 成绩记录
     * @return 创建的成绩记录
     */
    Grade createGrade(Grade grade);

    /**
     * 批量创建成绩记录
     * 
     * @param grades 成绩记录列表
     * @return 创建的成绩记录列表
     */
    List<Grade> createGrades(List<Grade> grades);
    
    /**
     * 获取考试的某个科目的所有学生成绩
     * 
     * @param examId 考试ID
     * @param subject 科目
     * @return 学生成绩列表
     */
    List<StudentGradeDTO> getExamSubjectGrades(Long examId, String subject);
    
    /**
     * 获取学生在某次考试中的所有科目成绩
     * 
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 科目成绩映射
     */
    Map<String, Double> getStudentExamGrades(Long studentId, Long examId);
    
    /**
     * 录入学生成绩
     * 
     * @param examId 考试ID
     * @param subject 科目
     * @param studentId 学生ID
     * @param score 分数
     * @return 成绩记录
     */
    Grade enterGrade(Long examId, String subject, Long studentId, Double score);
    
    /**
     * 批量录入学生成绩
     * 
     * @param examId 考试ID
     * @param subject 科目
     * @param studentGrades 学生成绩映射（学生ID -> 分数）
     * @return 成绩记录列表
     */
    List<Grade> batchEnterGrades(Long examId, String subject, Map<Long, Double> studentGrades);
    
    /**
     * 获取考试的所有学生成绩和排名
     * 
     * @param examId 考试ID
     * @return 学生考试成绩列表
     */
    List<StudentExamGradeDTO> getExamGradesWithRanking(Long examId);
    
    /**
     * 获取学生的历史考试成绩
     * 
     * @param studentId 学生ID
     * @return 考试成绩列表
     */
    List<ExamGradeDTO> getStudentHistoryGrades(Long studentId);
} 